home *** CD-ROM | disk | FTP | other *** search
/ MacHack 1997 / MacHack 1997.toast / Hacks / Hacks ’97 / ContextWarrior / source code / ContextualMenu.h < prev    next >
Text File  |  1997-06-27  |  7KB  |  191 lines
  1. /*
  2.     File:        ContextualMenu.h
  3.  
  4.     Contains:    <contents>
  5.  
  6.     Written by:    Guy Fullerton
  7.  
  8.     Copyright:    <copyright>
  9.  
  10.     Change History (most recent first):
  11.  
  12.          <6>     3/18/97    GBF     Add CMM trap number.
  13.          <5>     3/11/97    GBF     Add the Contextual Menu gestalt selector codes.
  14.          <4>     2/27/97    GBF     Adding trapwords to the declarations.
  15.          <3>     2/13/97    GBF     Remove DisplayContextualMenu.
  16.          <2>     1/14/97    GBF     Fixing the API for Backwards-compatibility INIT as well as the
  17.                                     display of the proper guide file name.
  18.         <0+>    10/15/96    GBF     Moved here from the Assistance tree.
  19. */
  20.  
  21.  
  22. /*
  23.     File:        ContextualMenu.h
  24.  
  25.     Contains:    The public ContextualMenu routines
  26.  
  27.     Written by:    deeje
  28.                 Guy Fullerton
  29.  
  30.     Copyright:    © 1995 by Apple Computer, Inc., all rights reserved.
  31.  
  32.     Change History (most recent first):
  33.  
  34.         <15>     7/29/96    GBF     Adding some #pragma import directives
  35.         <14>     7/28/96    GBF     Trying to make this thing Universal Headers compatible for
  36.                                     Harmony. Moving the plugin specific stuff to another file.
  37.                                     Removed a bunch of unnecessary #includes.
  38.         <13>     7/12/96    GBF     The last change comment (12) got screwed up; I'm fixing it.
  39.         <12>     7/12/96    GBF     Making the DisplayContextualMenu interface more modern.
  40.                                     replacing kShowBalloon and kShowHelp with some better enums.
  41.                                     Added some more enums.
  42.         <11>     4/11/96    GBF     Putting kExamineContextNoTimeout back, cuz I'm an idiot.
  43.         <10>     4/11/96    GBF     Moved kExamineContextNoTimeout out of here.
  44.          <9>      4/9/96    GBF     Add IsShowContextualMenuClick function. Cleaned up the API.
  45.          <8>     3/22/96    GBF     Added Timeout constant
  46.          <7>     3/14/96    GBF     Removing the AddContextualMenuItem routine. Adding typedef for
  47.                                     ContextualCommandPair. Adding some enums.
  48.          <6>      3/6/96    GBF     Adding the selection code parameter to AddContextualMenuItem
  49.          <5>      3/6/96    GBF     Added the AddContextualMenuItem routine.
  50.          <4>     2/28/96    GBF     DisplayContextualMenu now returns a SInt32
  51.          <3>     2/27/96    GBF     allow hierarchical menus within a contextual menu
  52.          <2>      2/7/96    arno    Changed Point to Point* to follow standard Maxwell conventions
  53.          <5>     12/5/95    djc     changing file type
  54.          <4>     8/29/95    djc        adding FindContextPopupArea
  55.         <3+>     8/29/95    djc     adding FindContextPopupArea()
  56.          <3>      8/1/95    djc     adding Balloon help and AppleGuide
  57.          <2>     7/31/95    djc        cleanup
  58.         <1+>     7/31/95    djc     cleanup
  59.          <1>     7/31/95    djc     initial check-in
  60. */
  61.  
  62.  
  63.  
  64. #ifndef    __CONTEXTUALMENU__
  65. #define    __CONTEXTUALMENU__
  66.  
  67. #include    <AppleEvents.h>
  68. #include    <Events.h>
  69. #include    <Menus.h>
  70.  
  71.  
  72.  
  73. /*
  74.  *
  75.  *     High Level Interfaces 
  76.  *
  77.  */
  78.  
  79. #ifdef __cplusplus
  80. extern "C"
  81. {
  82. #endif
  83.  
  84. #if PRAGMA_IMPORT_SUPPORTED
  85. #pragma import on
  86. #endif
  87.  
  88.  
  89.  
  90. enum {
  91.     // Contextual Menu Trap Number
  92.     _ContextualMenuDispatch                = 0xAA72
  93. };
  94.  
  95. enum
  96. {
  97.     // Gestalt Selectors
  98.     gestaltContextualMenuAttr            = 'cmnu',
  99.     gestaltContextualMenuPresent        = 0,
  100.     gestaltContextualMenuTrapAvailable    = 1
  101. };
  102.  
  103.  
  104.  
  105. enum
  106. {
  107.     // Values indicating what kind of help the application supports
  108.     kCMHelpItemNoHelp            = 0,
  109.     kCMHelpItemAppleGuide,
  110.     kCMHelpItemOtherHelp,
  111.     
  112.     // Values indicating what was chosen from the menu
  113.     kCMNothingSelected            = 0,
  114.     kCMMenuItemSelected,
  115.     kCMShowBalloonSelected,
  116.     kCMShowHelpSelected
  117. };
  118.  
  119.  
  120.     // This registers your application as a client of contextual menus.
  121.     // This is necessary so that the CMM can register your app as a
  122.     // real client; the CMM Enabler will use this registry as a means of
  123.     // deciding whether to provide the compatibility for a particular
  124.     // application.
  125. extern    pascal OSStatus InitContextualMenus(void)
  126.  TWOWORDINLINE(0x7001, 0xAA72);
  127.  
  128.     // This determines if the given event represents an action to invoke
  129.     // a Contextual Menu.  Pass every mouseUp or mouseDown event to this
  130.     // function.  When it returns true, the event represents a Contextual
  131.     // Menu invocation action.  When it returns false, the event doesn't
  132.     // represent an invocation.
  133. extern    pascal Boolean    IsShowContextualMenuClick(const EventRecord* inEvent)
  134.  TWOWORDINLINE(0x7002, 0xAA72);
  135.  
  136.     // This will draw and track a Contextual Menu.  Pass in the MenuRef to
  137.     // draw (or NULL if you just want the default, mostly empty one), the
  138.     // location of the mouse on the last Contextual Menu invocation event,
  139.     // a Boolean indicating whether there is Balloon Help content
  140.     // available for the item clicked upon, values indicating the
  141.     // guide content available for the item clicked, and an AEDesc
  142.     // which describes the item clicked (this can also be NULL).  Also
  143.     // pass pointers to a UInt32, and SInt16 and a UInt16 which will give
  144.     // you the results of the Contextual Menu selection.
  145.     //
  146.     // If the user doesn't select anything from the Contextual Menu, this
  147.     // returns userCanceledErr, sets outUserSelectionType to
  148.     // kCMNothingSelected, and sets outMenuID and outMenuItem to zero.
  149.     //
  150.     // If the user selects the Show Balloon item, this returns noErr,
  151.     // passes kCMShowBalloonSelected in outUserSelectionType, and
  152.     // sets both outMenuID and outMenuItem to zero.  You should then
  153.     // display a help balloon appropriate for the item clicked.
  154.     //
  155.     // If the user selects the Guide related item, this returns noErr,
  156.     // passes kCMShowHelpSelected in outUserSelectionType, and
  157.     // sets both outMenuID and outMenuItem to zero.  You should then
  158.     // open up a Guide file to a place appropriate for the item clicked.
  159.     //
  160.     // If the user selects one of your menu items, it returns noErr,
  161.     // passes kCMMenuItemSelected, and sets outMenuID and outMenuItem
  162.     // appropriately based upon the item chosen.
  163.     //
  164.     // If some other error occurred, an appropriate OSStatus will be
  165.     // returned.
  166. extern    pascal OSStatus    ContextualMenuSelect(MenuRef inMenuRef,
  167.                                         Point inGlobalLocation,
  168.                                         Boolean inBalloonAvailable,
  169.                                         UInt32 inHelpType,
  170.                                         ConstStr255Param inHelpItemString,
  171.                                         const AEDesc* inSelection,
  172.                                         UInt32* outUserSelectionType,
  173.                                         SInt16* outMenuID,
  174.                                         UInt16* outMenuItem)
  175.  TWOWORDINLINE(0x7003, 0xAA72);
  176.  
  177.                                           
  178. #if PRAGMA_IMPORT_SUPPORTED
  179. #pragma import off
  180. #endif
  181.  
  182. #ifdef __cplusplus
  183. }
  184. #endif
  185.  
  186.  
  187. #endif
  188.  
  189.  
  190.  
  191.